functions module

Module containing most of the utility functions for the binarycpython package

Functions here are mostly functions used in other classes/functions, or useful functions for the user

class binarycpython.utils.functions.Capturing(iterable=(), /)[source]

Bases: list

Context manager to capture output and store it

__enter__()[source]

On entry we capture the stdout output

__exit__(*args)[source]

On exit we release the capture again

binarycpython.utils.functions.bin_data(value, binwidth)[source]

Function that bins the data using the absolute value of binwidth using the following formula:

((0.5 if value > 0.0 else -0.5) + int(value / abs(binwidth))) * abs(binwidth)
Parameters
  • value – value that we want to bin

  • binwidth – width of the binning

Returns

binned value

binarycpython.utils.functions.binary_c_parameter_parse_description(parameter_dict)[source]

Function to parse the binary_c parameter dict

binarycpython.utils.functions.build_binary_c_parameter_section_table(section_name, section_dict)[source]

Function to build the binary_c parameter section table

Return type

str

binarycpython.utils.functions.build_binary_c_parameter_section_text(section_name, section_dict)[source]

Function to write the binary_c parameter section text as an rst table

Return type

str

binarycpython.utils.functions.calculate_total_mass_system(system_dict)[source]

Function to calculate the total mass of the system

binarycpython.utils.functions.call_binary_c_config(argument)[source]

Function to interface with the binary_c config file

Parameters

argument – argument for the binary_c config

Returns

raw output of binary_c-config

class binarycpython.utils.functions.catchtime[source]

Bases: object

Context manager to calculate time spent

__enter__()[source]

On entry we start the clock

__exit__(exc_type, exc_val, exc_tb)[source]

On exit we stop the clock and measure the time spent

binarycpython.utils.functions.check_if_in_shell()[source]

Function to check whether the script is running from a shell

binarycpython.utils.functions.command_string_from_list(list)[source]

Given a list, turn it into a quoted command string

binarycpython.utils.functions.conv_time_units(t)[source]

Converts time (t, in seconds, passing in as the only argument) to seconds, minutes or hours depending on its magnitude. Returns a tuple (t,units).

binarycpython.utils.functions.convert_bytes(size)[source]

Function to return the size + a magnitude string

binarycpython.utils.functions.convfloat(x)[source]

Convert scalar x to a float if we can, in which case return the float, otherwise just return x without changing it. Usually, x is a string, but could be anything that float() can handle without failure.

binarycpython.utils.functions.create_arg_string(arg_dict, sort=False, filter_values=False)[source]

Function that creates the arg string for binary_c. Takes a dictionary containing the arguments and writes them to a string This string is missing the ‘binary_c ‘ at the start.

Parameters
  • arg_dict (dict) – dictionary

  • sort (bool) – (optional, default = False) Boolean whether to sort the order of the keys.

  • filter_values (bool) – (optional, default = False) filters the input dict on keys that have NULL or function as value.

Return type

str

Returns

The string built up by combining all the key + value’s.

binarycpython.utils.functions.create_hdf5(data_dir, name)[source]
Function to create an hdf5 file from the contents of a directory:
  • settings file is selected by checking on files ending on settings

  • data files are selected by checking on files ending with .dat

TODO: fix missing settings files

Parameters
  • data_dir (str) – directory containing the data files and settings file

  • name (str) – name of hdf5file.

Return type

None

binarycpython.utils.functions.datalinedict(line, parameters)[source]

Convert a line of data to a more convenient dictionary.

Parameters
  • string (line = a line of data as a) –

  • names (parameters = a list of the parameter) –

Note

If the parameter is a floating point number, it will be converted to Python’s float type.

binarycpython.utils.functions.example_parse_output(output, selected_header)[source]

Function that parses output of binary_c. This version serves as an example and is quite detailed. Custom functions can be easier:

This function works in two cases: if the caught line contains output like ‘example_header time=12.32 mass=0.94 ..’ or if the line contains output like ‘example_header 12.32 0.94’ Please don’t the two cases.

You can give a ‘selected_header’ to catch any line that starts with that. Then the values will be put into a dictionary.

Tasks:
  • TODO: Think about exporting to numpy array or pandas instead of a defaultdict

  • TODO: rethink whether this function is necessary at all

  • TODO: check this function again

Parameters
  • output (str) – binary_c output string

  • selected_header (str) – string header of the output (the start of the line that you want to process)

Return type

dict

Returns

dictionary containing parameters as keys and lists for the values

binarycpython.utils.functions.filter_arg_dict(arg_dict)[source]

Function to filter out keys that contain values included in [‘NULL’, ‘Function’, ‘’]

This function is called by get_defaults()

Parameters

arg_dict (dict) – dictionary containing the argument + default key pairs of binary_c

Return type

dict

Returns

filtered dictionary (pairs with NULL and Function values are removed)

binarycpython.utils.functions.format_number(number)[source]

Function to take a number, express format it in scientific notation, and remove the trailing 0 if the exponent is 0

binarycpython.utils.functions.get_ANSI_colours()[source]

Function that returns a dictionary with text-colors in ANSI formatting

binarycpython.utils.functions.get_arg_keys()[source]

Function that return the list of possible keys to give in the arg string. This function calls get_defaults()

Return type

list

Returns

list of all the parameters that binary_c accepts (and has default values for, since we call get_defaults())

binarycpython.utils.functions.get_defaults(filter_values=False)[source]

Function that calls the binaryc get args function and cast it into a dictionary.

All the values are strings

Parameters

filter_values (bool) – whether to filter out NULL and Function defaults.

Return type

dict

Returns

dictionary containing the parameter name as key and the parameter default as value

binarycpython.utils.functions.get_help(param_name='', print_help=True, fail_silently=False, store_memaddr=None)[source]

Function that returns the help info for a given parameter, by interfacing with binary_c

Will check whether it is a valid parameter.

Binary_c will output things in the following order: - Did you mean? - binary_c help for variable - default - available macros

This function reads out that structure and catches the different components of this output

Parameters
  • param_name (str) – name of the parameter that you want info from. Will get checked whether its a valid parameter name

  • print_help (bool) – (optional, default = True) whether to print out the help information

  • fail_silently (bool) – (optional, default = False) Whether to print the errors raised if the

  • valid (parameter isn't) –

Return type

Optional[dict]

Returns

Dictionary containing the help info. This dictionary contains parameter_name, parameter_value_input_type, description, optionally macros

binarycpython.utils.functions.get_help_all(print_help=True, store_memaddr=None)[source]

Function that reads out the output of the return_help_all API call to binary_c. This return_help_all binary_c returns all the information for the parameters, their descriptions and other properties. The output is categorised in sections.

Parameters

print_help (bool) – (optional, default = True) prints all the parameters and their descriptions.

Return type

dict

Returns

returns a dictionary containing dictionaries per section. These dictionaries contain the parameters and descriptions etc for all the parameters in that section

binarycpython.utils.functions.get_help_super(print_help=False, fail_silently=True)[source]

Function that first runs get_help_all, and then per argument also run the help function to get as much information as possible.

Parameters
  • print_help (bool) – (optional, default = False) Whether to print the information

  • fail_silently (bool) – (optional, default = True) Whether to fail silently or to print the errors

Return type

dict

Returns

dictionary containing all dictionaries per section, which then contain as much info as possible per parameter.

binarycpython.utils.functions.get_numerical_value(string)[source]

Function to turn a string to a numerical value

binarycpython.utils.functions.get_size(obj, seen=None)[source]

Recursively finds size of objects

From https://github.com/bosswissam/pysize

binarycpython.utils.functions.get_username()[source]

Function to get the username of the user that spawned the current process

binarycpython.utils.functions.hostnames()[source]

Return a list of possible hostnames for this machine

binarycpython.utils.functions.imports()[source]

Generator that generates the names of all the modules that are loaded in the globals

binarycpython.utils.functions.is_capsule(o)[source]

Function to tell whether object is a capsule

binarycpython.utils.functions.isfloat(x)[source]

Function to return True if the “number” x, which could be a string, is an float, otherwise return False.

Parameters

x (Union[str, float, int]) – string float or int that we will attempt to convert to an float value.

binarycpython.utils.functions.isint(x)[source]

Function to return True if the “number” x, which could be a string, is an int, otherwise return False.

Parameters

x (Union[str, float, int]) – string float or int that we will attempt to convert to an int value.

binarycpython.utils.functions.load_logfile(logfile)[source]

Experimental function that parses the generated log file of binary_c.

This function is not finished and shouldn’t be used yet.

Tasks:
  • TODO: fix this function

Parameters

logfile (-) – filename of the log file you want to parse

Returns:

Return type

None

binarycpython.utils.functions.make_build_text()[source]

Function to make build text

Return type

str

Returns

string containing information about the build and the git branch

binarycpython.utils.functions.mem_use()[source]

Return current process memory use in MB. (Takes no arguments)

Note: this is per-thread only.

binarycpython.utils.functions.now(now_object=None, style=None, custom_format=None)[source]

convenience function to return a string of the current time, using the format %m/%d/%Y %H:%M:%S

Parameters
  • style – if “nospace” then return the date/time with the format %Y%m%d_%H%M%S, else use format %m/%d/%Y %H:%M:%S

  • custom_format – if set, uses this as a format rather than whatever is set by default or in the style variable

binarycpython.utils.functions.output_lines(output)[source]

Function that outputs the lines that were received from the binary_c run, but now as an iterator.

This function filters out lines that are empty.

Parameters

output (str) – raw binary_c output

Return type

list

Returns

Iterator over the lines of the binary_c output

binarycpython.utils.functions.pad_output_distribution(dist, binwidth)[source]

Given a distribution, dist (a dictionary), which should be binned every binwidth (float), fill the distribution with zeros when there is no data. Note: this changes the data in place.

Parameters
  • dist (dict) – dictionary containing the distribution data.

  • binwidth (float) – binwidth that is used to fill the distribution with 0 in places where there is no value/key.

binarycpython.utils.functions.quotewrap(list)[source]

Given a list, wrap each item in double quotes and return the new list

binarycpython.utils.functions.remove_file(file, verbosity=0)[source]

Function to remove files but with verbosity

Parameters
  • file (str) – full file path to the file that will be removed.

  • verbosity (int) – current verbosity level (Optional)

Return type

None

Returns

the path of a sub directory called binary_c_python in the TMP of the file system

binarycpython.utils.functions.temp_dir(*child_dirs, clean_path=False)[source]

Function to create directory within the TMP directory of the file system, starting with /<TMP>/binary_c_python-<username>

Makes use of os.makedirs exist_ok which requires python 3.2+

Parameters
  • *child_dirs – str input where each next input will be a child of the previous full_path. e.g. temp_dir('tests', 'grid') will become '/tmp/binary_c_python-<username>/tests/grid'

  • *clean_path (optional) – Boolean to make sure that the directory is cleaned if it exists

Return type

str

Returns

the path of a sub directory called binary_c_python in the TMP of the file system

binarycpython.utils.functions.timedelta(delta)[source]

Function to convert a length of time (float, seconds) to a string for human-readable output.

binarycpython.utils.functions.trem(dt, count, dn, n)[source]

Estimate time remaining (seconds) given a differential time and count (i.e. progress = count/n).

Parameters
  • dt – is the time since the last call.

  • count – is the current progress count.

  • dn – is the number run since the last call.

  • n – is the total number required.

binarycpython.utils.functions.write_binary_c_parameter_descriptions_to_rst_file(output_file)[source]

Function that calls the get_help_super() to get the help text/descriptions for all the parameters available in that build.

Writes the results to a .rst file that can be included in the docs.

Parameters

output_file (str) – name of the output .rst file containing the ReStructuredText formatted output of all the binary_c parameters.

Return type

None